MacFormat 1994 November

home *** CD-ROM | disk | FTP | other *** search

/ MacFormat 1994 November / macformat-018.iso / Utility Spectacular / Developer / demoCDEF ƒ / About CDEF's next >

Wrap

Text File | 1994-07-17 | 14.8 KB | 358 lines | [TEXT/KAHL]

/*---------------------------------------------------------------------- Revision History: v1.0 June 1994 - first distribution v1.01 July 1994 - 3D Buttons now supports multi-line titles - GroupBox uses Control Max instead of RefCon for true height of box (templates must be changed). - both slider controls have a correction to tracking logic when mouse is moved past end of slider. Now, tracking will not resume until mouse is moved back to the thumb. ------------------------------------------------------------------------ Here is a collection of 9 CDEF's (Control Definitions) and some other bits of source code to demo their use. This stuff is also pretty much un-documented - this file and comments in the source is about it. I've learned to appreciate the job that Tech Writers do - I've started some "real" documentation, but it never seems complete. Read the source code - especially the .r file - it might help you understand how to use these CDEF's. There are no restrictions on this (as far as I know and care), use it if you wish. If you find some use for this code, I'd love to know about it. This code is absolutely unwarranted. I'm sure that there are some errors somewhere, but it does seem to work. I'm uploading this because when I was learning (I still am…) how to program on the Mac, I learned a lot from source code that others uploaded. Hopefully, this will help someone else learn something about the Mac. The source code for the actual CDEF's is not included here, but you can find the CDEF's as code resources in file xDEF.rsrc. I'd like to see the CDEF's "shaken out" a bit before I upload the source - if anyone wants it. Just let me know if I should upload it. Jim Stout CompuServe : 73240,2052 AppleLink : WRQ AOL : JasG Internet : JimS@WRQ.COM ------------------------------------------------------------------------ A few weeks back I was reading the Human Interface volume of Inside Mac and it struck me as funny that Apple refers to various controls (used throughout the MacOS) as "not supported by the Toolbox". Controls like "little arrow" controls used to set Date & Time, Memory etc. ,"Slider Controls" like those in the Sound or Brightness control panels and a "Progress Bar" are simply are not to be found in the Toolbox. Apple simulates controls by displaying appropriate PICT's and handling mouse events in a dialog filter (I think). I realized that over the past couple of years, I had written some of those controls (the rest are hot off my coding pad). One of the CDEF's, 104 "Tog Button" is a little different. This is explained below in the section "About Tog Buttons". You can also get this type of control with variation code 4 and the 3D Buttons CDEF. All of these controls will work with System 6 or System 7 - the only caveat is that the PopUpMenu control requires PopUpMenuSelect. I have tested them on machines from a MacPlus through a PowerMac 7100. (Actually, I've tested these as far back as System 3.2 - I've gotta do something with that original 128k Mac with MacPlus ROM's that is sitting in the corner...) If possible, all except the GroupBox and PopUpMenu controls will use 32bit ColorQuickdraw and offscreen GWorlds to support color. As far as I can tell, they all handle low memory situations by refusing to draw themselves. Let me know if you see any problems. All controls with titles honor the "useWindFont" variation code (to draw in a non-System font), will properly color themselves if a 'cctb' resource is present and when disabled, will appear in the proper System 7 style gray (if possible). I have not written these to support non-roman script systems. Other variation codes, sizes and non-standard control template values are listed below. ------------------------------------------------------------------------ The controls are: procID Name Function ------ ----------- ------------------------------------------------ 100 GroupBox draws a titled box, text in upperleft 101 PopUp Menu system 7 style popup menu control 102 Spinner "little arrows" control 103 Date & Time Date & Time control using "little arrows" 104 Tog Button a new type of "one or many" control 105 HSlider horizontal slider control 106 VSlider vertical slider control 107 3D Buttons a 3d replacement for the standard button CDEF 108 Progress Bar a progress bar CDEF Variation codes & size ====================== (min h & w is minimum required height & width for the control rect when using Chicago 12 font) CDEF varCode min h & w Result --------- ---------- ---------- ------------------------------------ GroupBox 0 Draws a solid frame 1 Draws a dotted frame 2 * not used * 4 * not used * 8 Use the Window font for title NOTE: To avoid problems with "layering" of this control over or under the contents of a box, set the height of this control to 16 or so, then put the height you REALLY want in the contrlMax field of the CNTL template. The control rect (used by the Dialog Manager) will not obstruct other controls. However, when the control draws - it will use the height value from the contrlMax field. ------------------------------------------------------------------------ PopUp Menu 19 x nn (see IM VI or docs for Apple CDEF 63 19 x 25 for "triangle only" menu NOTE: if the menu has styled text items, the height may need to be greater than 19. Unlike the Apple CDEF 63, this control will: - behave the same with System 6 & 7 - properly handle colored menus It DOES NOT support: - Icons or cmd keys - Styled text titles ------------------------------------------------------------------------ Spinner 0 18 x nn Small, as in "Date & Time" Control panel 1 25 x nn Large, as in "Memory" Control panel 2 * not used * 4 * not used * 8 Use the Window font for drawing NOTE: use 18 x 11 or 25 x 15 to get arrows only ------------------------------------------------------------------------ Date & Time 0 18 x 160 Date left, Time right justified 1 18 x 80 Date only, left justified 2 18 x 80 Time only, left justified 4 37 x 80 Both on 2 lines, date over time 8 Use the Window font for drawing NOTE: non-standard date or time separator characters may need a larger rect. ------------------------------------------------------------------------ Tog Button 0 18 x nn Normal button title 1 * not used * 2 * not used * 4 * not used * 8 Use the Window font for title ------------------------------------------------------------------------ HSlider 0 24 x 121 As in the "Brightness" Control panel 1 "Thumb" is drawn in gray pattern 2 Scale drawn in bg color (not filled) 4 Scale drawn in gray pattern 8 * not used * ------------------------------------------------------------------------ VSlider 0 105 x 24 As in the "Sound" Control panel 1 "Thumb" is drawn in gray pattern 2 Scale drawn in bg color (not filled) 4 "Thumb" will not "snap" to tick mark 8 Scale is blank, no numbers, no marks NOTE: ht is 12*divisions + 21 (see below) ------------------------------------------------------------------------ 3D Buttons 0 any x any draws a push button 1 draws a checkbox 2 draws a radiobutton 4 draws a Tog Button control 8 Use the Window font for title NOTE: This control should behave just like the standard CDEF 0 when running in 1 bit (B&W) mode OR if the background is white. If running on a non-white background, this CDEF will draw "3 D" controls. Colors are taken from a 'cctb' resource. ------------------------------------------------------------------------ Progress Bar 0 any x any draws a horizontal progress bar 1 draws a vertical progress bar 2 draws a rounded, 3D progress bar 4 not used 8 not used -------------------------------------------------------------------- Control Drawing =============== All control drawing is clipped to the control rect, so it should be pretty obvious if you have a control rect that is too small. Non-standard control RefCon usage =================================== Note: Several of these controls use the control refcon field. They are: PopUp Menu - use of refcon is identical to Apple's CDEF 63 - not used by control after initialization. Spinner - refcon may be used to indicate a DITL item for an edit item to update as the control value changes. - not used by control after initialization. VSlider - refcon may be used to indicate the number of divisions but will default to 7 divisions. - not used by control after initialization. DateTime - refcon is the "value" of the control. It is updated by the control. - ** USED ** by control after initialization - see below. Non-standard control template usage =================================== GroupBox does not use min, value or rfCon. max is used for the true height of the control. PopUp Menu (see Inside Mac VI or other docs for Apple CDEF 63) Does NOT support menu icons or cmd-keys, the menu can have them, but the control will not draw them. Spinner standard use of min, max and value. the control refCon field can be a DITL item number for an editText item to update with the control value. Date & Time does not use min, max contrlValue indicates hilited digits 1 hours 2 minutes 3 AM/PM 6 month (6,7,8 match user order from Control Panel 7 day and may not have these meanings) 8 year contrlRfCon is seconds as passed to GetDateTime(), Secs2Date() and Date2Secs() calls. This is the "value" that the control adjusts. Use GetCRefCon() to retrieve the "date time" value and SetCRefCon() to set it. HSlider min = 0, max = 100 - these are set by the control. value returned will range from min to max VSlider refCon is used to indicate 'number of divisions' from 2-20. Default is 7 divisions with tick marks from 0-7. min = 0 max = 12*"number of divisions" The value returned will range from min to max. The control "thumb" will "snap" to a tick mark. This means that the value will always be 12*tick mark. To avoid the "snap" behavior, use varCode 4. 3D Buttons standard use of all fields, but with an additional variation code for "Tog" buttons. Progress Bar standard use of all fields ----------------------------------------------------------------------- About "TogButtons" ----------------------------------------------------------------------- In early November 1991, I ran across an article in the October 1991 "Apple Direct" by Bruce Tognazzini - Apple's human interface guru. Each month Tog would write a column dealing with HI issues. The article that caught my eye back then was titled "Case Study: One or more Buttons". I don't think that I can legally include Tog's article with this bit of code, but you can find it on many of the Apple Developer CD's in the Periodicals:Apple Direct:Apple Direct Oct '91:Tog folder. It also is in his book "Tog on Interface" as chapter 36. To summarize, Tog wrote about the design and usability testing of a new interface element that he called "One or more Buttons" - essentially a control that was part Checkbox and part Radio button. A group of Checkboxes can all be "Off" and a group of Radio buttons can only have one "On" value. What was needed was a group that MUST have ONE "On" control but could have many "On" controls - a "One or more Button". Tog's design for what I call "Tog Buttons" is a cross between a Radio button and a Checkbox. The control is a diamond (a Checkbox rotated 90 degrees) with a diamond shaped indicator (like the circular indicator in a Radio button). The behavior is also a cross between the two other controls. If only one control is ON, then clicking on it turns that control OFF and turns on an adjacent control (just like a pair of radio buttons), if one or more of the controls is ON, then others can be toggled (just like a checkbox). Another twist on the behavior is that if only one control is ON, a click on that control will turn if OFF, and turn on the one just above (or to the left of) it. When the first (or last) control is reached, the direction reverses, turning on the one just below (or to the right). Tog likened this behavior to that of a drop of mercury when you press on it with a finger (but without the toxicity!). The behavior is such that with a single ON button, clicking on just that button, causes it to "jump" up (or leftward). If you keep chasing the single ON button, it will keep "jumping" up until it must reverse direction and start "jumping" down. Unless you are "chasing" a button like this, when only one button is ON, the default behavior is to jump UP (or to the left). To see this, try the TogDemo program and you will see what I mean. For some reason, this appealed to me as an interesting project and I spent a fun afternoon implementing Tog's idea. I ended up creating a CDEF to implement the control described by Tog and a couple of routines in C to support the desired behavior of "Tog Buttons". ----------------------------------------------------------------------- How to use a Tog Button in a dialog =================================== Obviously, using a Tog Button is only needed if you have a situation that has a group of items that requires "One or Many" values. An example might be a search : - Search ----------------- | | | <•> C files (.c) | | < > Include files (.h) | | < > Resource files (.r) | | | -------------------------- The file cdefDemo.c shows how to use "Tog Buttons", but here is a brief list. 1. Include the files TogLib.c/TogLib.h in your project. 2. Define the group of "Tog Buttons" in your dialog resource. 3. DITL item numbers MUST be successively numbered for each group of "Tog Buttons". This is IMPORTANT! 4. After calling GetNewDialog, but before calling ModalDialog, call initTogButtons() for each group of "Tog Buttons". 5. When a "Tog Button" is clicked, call setTogButtons() for that group of "Tog Buttons". 6. When a non-Tog Button control is clicked, do whatever is needed, then call resetTogButtons() for each group of "Tog Buttons". This step simply insures that the next click on a "Tog Button" will "go up". 7. Use regular calls to GetDItem() and GetCtlValue() to retrieve the control values for "Tog Buttons". The TogLib routines are the key to maintaining consistent behavior of the "Tog Buttons". TogLib.h has a short description of each routine. ----------------------------------------------------------------------*/